Mapi Contents
MAPI Delphi VCL

Contents

Class Definitions

TMapi Class

Properties

Methods

TMapiMsg Class

Properties

Methods

Using TMapi VCL


MAPI Classes

The MAPI VCL contains five classes :

TMapi is the master class and should only be instantiated once..  It encompasses information about the MAPI session such as session ID, logon method, etc.   It includes as a member the TEnvelopeList class.

TEnvelopeList encapsulates the the user's inbox into a TList of mail envelopes labelled "inbox".

TMapiMsg class encapsulates a single message.  As many of these objects  as desired may be instantiated.  It contains information abaout each message (in- or out-bound) such as the subject or the recipient list.  It includes the following two classes as members:

TAddressList contains a TList of receipients.  There will be one TAddressList for "Recipients" and another for "CCRecipients".

TFileList contains a TList of attachments for a message.


TMapi Properties
TMapi Class Properties

Class 	Methods

Design Time

LogonU I

TRUE will cause a dialog box to be displayed to facilitate logging on to MS-Mail if an attempt to log on fails; FALSE will not display a dialog box.

NewSession

TRUE will cause the logon to establish a new MAPI session regardless of the current MS-Mail status; FALSE will cause the log on to piggy-back on a currently in use session.

DownLoadMail

TRUE will cause MS-Mail to download new mail to the user's mail account inbox during log on; FALSE will not download new mail.

MailID

 Optional; the MS-Mail user ID of the account to log on to.  This will be used as a default ID by the MAPI VCL if the first parameter of the Logon method is null.

Run Time

SessionID

SessionID is the session ID returned during a successful attempt to log onto the MS-Mail system. Type: Longint

UserID

The MS-Mail ID of th euser currently logged onto MS-Mail through this control. Type: Pascal-style string

Inbox

Inbox is the special object instantiated by TMapi to hold the list of envelopes in the user's MS-Mail inbox (see TMapi Methods).  Type: TEnvelopeList

Inbox.Originator

The display name of the originator of the message in the envelope designated by the last Inbox.SetIndex method.  Type: Pascal-style string

Inbox.ReceivedDate

The date the message in the envelope designated by the last Inbox.SetIndex method was received.  Type: TDateTime

Inbox.Subject

The subject of the message in the envelope designated by the last Inbox.SetIndex method.  Type: Pascal-style string

Inbox.MsgID

The MS-Mail message ID of the envelope designated by the last Inbox.SetIndex method.  Type: Pascal-style string

Inbox.Opened

TRUE if  the envelope designated by the last Inbox.SetIndex method has been read previously.  Type: Boolean

Inbox.Count

The number of envelopes contained in the Inbox list.  Type: Integer


TMapi
TMapi Class

Properties	Methods

TMapi is the master class for the MAPI Delphi VCL.  It must be instantiated to to log on to the MS-Mail system and construct a session ID.  It must stay in scope as long as there is a message instance still open.  It will generate one instance of the TEnvelopeList class called "inbox".  Inbox will contain a list of the envelope information for each peice of mail in the user's MS-Mail inbox.


TMapi Methods

Class	Properties

MapiInstance := TMapi.Create(TComponent)

Create instantiates an instance of the TMapi class.  It requires a fixed parameter - the word TComponent. Returns an instance hanndle for the instantiation.

MapiInstance.Destroy

Destroy removes the instantiation of a Mapi object.  It will release all allocations related to the object and if they user has not logged off, it will automatically logg off MS-Mail.

boolean := MapiInstance.Logon(sUserID, sPassword)

Logon logs the user onto MS-Mail.  It requires two Pascal-style strings: the MS-Mail user ID and the user's MS-Mail password.  Either or both paramters may be null ( '' ).  If sUserID is null, Logon will utilize the UserID property.  Returns a TRUE/FALSE completion status.

boolean := MapiInstance.Logoff

Logoff logs the user off the MS-Mail system. Returns  a TRUE/FALSE completion status.

boolean := MapiInstance.Inbox.Load( ClearInbox, UnReadMailOnly )

Inbox.Load loads envelope information into the inbox list.  Two boolean parameters are required.  ClearInbox TRUE cuases the inbox list to be cleared before loading; FALSE adds envelopes to the existing list.  UnReadMailOnly TRUE will only add envelopes for messages which have not been read in the MS-Mail system; FALSE will add all messages in MS-Mail to the inbox list.  Returns  a TRUE/FALSE completion status.

boolean := MapiInstance.Inbox.SetIndex( iIndex )

Inbox.SetIndex sets the pointer to an envelope within the inbox list.  Index is a zero-based integer.  Returns TRUE if the index is set and FALSE if the index is out of range.

boolean := MapiInstance.Inbox.Delete

Inbox.Delete removes the enveloped pointed to by Inbox.Index from the inbox list. Returns  a TRUE/FALSE completion status.

boolean := MapiInstance.Inbox.OpenEnvelope( ihMsg )

Inbox.OpenEnvelope reads the peice of mail identified by the the Inbox.Index.  The information from this message is placed in the TMapiMsg instance indicated in the parameter ihMsg.  Returns  a TRUE/FALSE completion status.


TMapiMsg
TMapiMsg Class

Properties	Methods

The TMapiMsg class is a container for an MS-Mail message.  It may be either a message being composed or a message being read.  each TMapiMsg may contain only one message, but the user may instantiate as many TMapiMsg objects as desired.  Usually, the user will have one object for composing messages and one for reading the current message in the inbox list.

TMapiMsg instantiates two occurrances of the TAddressList class.  These two objects contain the recipient list and the copy-to recipient list; they are named Recipient and CCRecipient.

TMapiMsg also instantiates one copy of the TFileList class.  This is a list of file attachments for the message.


TMapiMsg Properties

Class	Methods

Run Time

MsgID

The MS-Mail message ID for the message; null if this is a compose message.  Type: Pascal-style string

Subject

The subject of the message.  Type: Pascal-style string

ReceivedDate

The date this message was received by the user; null if this a compose message.  Type: TDateTime

ReceiptRequested

TRUE if this message requires a return receipt on compose or sent a receipt when this message was read.  Type: Boolean

MessageType

The MS-Mail message type if this is not a standard interpersonal mail message (IPM).  Type: Pascal-style string

MessageText

The text of the message.  This pointer is provided if this message has been read via the Inbox.OpenEnvelope method.  The user must intialize this pointer to a valid existing pointer for the message text when composing a message.  Type: Pchar (null-terminated string)

OriginatorName

The display name of the originator of this message (i.e. - "Smith, John" rather than "SMITHJ"); null if this is a compose message.  Type: Pascal-style string

OriginatorAddress

The MS-Mail address of the originator of this message (i.e. - "MS:CONCERT/RSMPO01/SMITHJ"); null if this is a compose message.  Type: Pascal-style string

Recipient
CCRecipient

An object containing the list of recipients for this message.  There is one instance each for Recipients (direct recipients) and CCRecipients (copy-to recipients).  Type: TAddressList

Recipient.DisplayName
CCRecipient.DisplayName

The MS-Mail display name of the recipient indicated by the last Recipient.SetIndex / CCRecipient.SetIndex method (i.e. - "Smith, John" rather than "SMITHJ").  Type: Pascal-style string

Recipient.Address
CCRecipient.Address

The MS-Mail address of the receipient indicated by the last Recipient.SetIndex / CCRecipient.SetIndex method (i.e. - "MS:CONCERT/RSMPO01/SMITHJ").  Type: Pascal-style string

Recipient.Count
CCRecipient.Count

The number of receipients listed in the object.  Type: Integer

Attachment

An object containing the list of attachments for this message.  Type: TFileList

Attachment.DisplayName

The title to be displayed under this attachment in the MS-Mail message.  Type: Pascal-style string

Attachment.FileName

Fully qualified path and filename identifying the file attachment (i.e. - "C:\MYDIR\MYWORD.DOC").  Type: Pascal-style string

Attachment.Position

The character position at which the attachment is placed in the message text.  This is a zero-based number.  Type: LongInt

Attachment.OleType

A number indicating the type OLE interaction, if any, to be used by MS-Mail when reading this attachment;  0 = no-OLE, 1 = MAPI OLE, 2 = MAPI static OLE.  Type: LongInt

Attachment.Count

The number of attachments contained in the attachment list.  Type: Integer


TMapiMsg Methods

Class	Properties

MsgInstance := TMapiMsg.Create( hSession )

Create instantiates an object for use as a message container.  It returns the instance handle.  The hSession parameter is an Longint which is the valid MS-Mail session ID from the associated TMapi object.

MsgInstance.Destroy

Destroys the MsgInstance of TMapiMsg and releases all associated allocations.

boolean := MsgInstance.Send

Send transmits the message contained in MsgInstance to the MS-Mail system.  It returns TRUE id the send was succesful or FALSE if the send failed.

boolean := MsgInstance.NewMessage

Erases all information in the MsgInstance message container.  This does not instantiate new instance, it merely resets the indicated instance.  Returns TRUE is successful or FALSE if it failed

boolean := MsgInstance.Save

This method saves the TMapiMsg instance in the users Inbox for future use.  Returns TRUE if successful or FALSE if it failed to delete.

boolean := MsgInstance.Delete

This method deletes the message identified by TMapiMsg instance in the users Inbox.  It does not destroy the instance of TMapiMsg which may be used until destroyed.  Returns TRUE if successful or FALSE if it failed to delete.

boolean := MsgInstance.Recipient.SetIndex( Index )
boolean := MsgInstance.CCRecipient.SetIndex( Index )

Recipient.SetIndex / CCRecipient.SetIndex sets the pointer to a recipient within the appropriate list.  Index is a zero-based integer.  Returns TRUE if the index is set and FALSE if the index is out of range.

boolean := MsgInstance.Recipient.Add( Name, Address)
boolean := MsgInstance.CCRecipient.Add( Name, Address)

Adds a new name and address to the appropriate list.  Name and Address are Pascal-style strings.  Either Name or Address are required.  The Add method will automatically resolve the name in MS-Mail.  The object Index property points to this recipient.  Returns TRUE if the Name was successfully resolved and added to the list or FALSE if the resolve failed.

boolean := MsgInstance.Recipient.Delete
boolean := MsgInstance.CCRecipient.Delete

Deletes from the list the recipient pointed to by the last SetIndex method for the appropriate list.  Returns TRUE if successful or FALSE if it failed to delete.

boolean := MsgInstance.ReplaceRecipients(RecipientList)

This method replaces the current recipient list with names picked from the Global Address Book.  RecipientList is a recipient object from an instance of TMapiMsg.  It allows the user to pick names and add them to a list and then completely replace the RecipientList object.  Returns TRUE if successful or FALSE if it failed to delete.

boolean := MsgInstance.Attachment.SetIndex( Index )

Attachment.SetIndex sets the pointer to an attachment within the list.  Index is a zero-based integer.  Returns TRUE if the index is set and FALSE if the index is out of range.

boolean := MsgInstance.Attachment.Add( DisplayName, FileName,  Position, OleType)
boolean := MsgInstance.Attachment.Add( DisplayName, FileName,  Position, OleType)

Adds a new attachment to the list.  DisplayName and FileName are Pascal-style strings, Position and OleType are Longint type (see TMapiMsg Properties).  DisplayName may be null ( '' ).  Returns TRUE if the attachment was successfully added to the list or FALSE if the add failed.

boolean := MsgInstance.Attachment.Delete

Deletes from the list theattachment pointed to by the last SetIndex method for the list.  Returns TRUE if successful or FALSE if it failed to delete.


Using TMapi
Using the MAPI Delphi VCL

Establishing a Session

First, a session must be established with MS-Mail.  The user accomplishes this by instantiating a TMapi object and logging onto MS-Mail.

Place a copy of the TMapi control on your form.
result := myMapi.Logon ( 'My Name', 'My Password' );

Reading Mail

To read mail, the user must first load the Inbox list.

result := Mapi1.Inbox.Load ( TRUE, FALSE );

Then he/she must select the mail item (envelope) to be read.

result := Mapi1.Inbox.SetIndex ( 2 );

Finally, the user must establish a message container and open an envelope into that container.

VAR
   myReadMsg : TMapiMsg;
BEGIN
   myReadMsg := TMapiMsg.Create ( Mapi1.SessionID );
   result := Mapi1.Inbox.OpenEnvelope ( myReadMsg );

The user may retreive parts of the message by referencing the appropriate property or method

varSubject := myReadMsg.Subject;
myReadMsg.Recipient.SetIndex ( 0 );
varPerson := myReadMsg.Recipient.DisplayName;

Sending Mail

To send mail, the user must establish a message container,

myComposeMsg := TMapiMsg.Create ( myMapi.SessionID );

Next, he/she must populate the message components.

myComposeMsg.Subject := 'This is the subject of the message';
pText := strAlloc ( size );
StrPCopy ( pText, 'My message text goes here.' );     { this is one method, there are others }
result := myComposeMsg.MessageText := pText;
result := myComposeMsg.Recipient.Add ( 'Washington, George', '' );
result := myComposeMsg.CCRecipient.Add ( 'Washington, Martha', '' );

Lastly, the message must be sent.

result := myComposeMsg.Send;

Terminating MAPI Session

To terminate a MAPI session the user should log off first.  However, if the user fails to do so, when a TMapi object is destroyed, it will automatically log off.

result :=Mapi1.Logoff;
Mapi1.Destroy;